Valid for Sitecore 5.3.1

Documentation (Sitecore 5.3)

1. Introduction

The Sitecore Poll module allows you to create polls on your site. All you need to do is install the Poll module, create one or more poll items, and add the poll controls to your client pages.

Settings application:

/upload/poll_module_13.png

/upload/poll_module_14.png

You can easily manage polls on your site from the Sitecore client and create polls for both Extranet users and Sitecore editors.

2. Installation

In order to install the Sitecore Poll Module, you need to install a package, modify the web.config file and perform a full publish.

The Poll Module is distributed as a standard Sitecore package; hence in order to start using it, you should install the package. Please, refer to the 'Installing Modules and Packages' article if you are not familiar with the standard Sitecore Packager tool.

The following Items are added during the installation:

The ‘Polls’ folder with a sample poll in ‘/sitecore/content’
The ‘Poll module’ folder with a number of templates in the templates folder.

After the package installation, you need to make changes to the web.config and commands.config files. Follow the steps below.

Step1:

Add the lines below to the <controlSources> section to let Sitecore know the location of the xml controls:

Step2:

Add the line below to the <ui><references> section:

<reference>/bin/Sitecore.Modules.Poll.dll</reference>

This will active the sheer UI forms which maintain the Poll module functionality.

Step3:

Add the following line to the <uiDeleteItems> section:

...................................

...................................

</uiDeleteItems>

Step4:

Add the following commands to the commands.config file which is located at the App_Config folder of the Sitecore solution:

Perform the full publishing. It is highly recommended to republish the site after the module installation.

3. General Description

The installation process adds a number of Items, Templates, and controls to your Sitecore client.

templates/Poll Module folder:

Poll – for creating Poll Items.
Poll Folder – for creating Items which contain Polls.
Poll option – for creating Items which contain poll variants.
Poll settings – for creating settings Item.

The following web controls are installed:

Folder Viewer – the editor for the Poll folder Item.
Poll Portlet – a portlet for the Sitecore Today application.
Poll Wizard – a wizard for the Poll creation.
Poll Info – a viewer for the Poll Items.
Poll Option – a Poll wizard service control.
Voting – a Poll web control for backend pages.
VotingArchive – a Poll Archive web control for backend pages.
There is a setting item in ‘/sitecore/system/Modules/Poll/settings’. It contains information about connection string and the Poll of the day.

In the ‘content/Polls’ Item, you can see a sample Poll called ‘Do you watch TV’. If you select the Polls Item, you will see the Editor on the right pane. You can see the Poll viewer when you choose the ‘watch TV’ Item.

/upload/poll_module_17.png

4. Creating a New Poll Item

Select the ‘content/Polls’ Item, click the ‘Add’ button in the Editor window. The Poll wizard will start.

Follow the instructions to create a new Poll.

The Poll name Field holds the name of the Item. The Poll title Field holds the poll title shown in the Editor.

Enter the name and title of the Poll options.

Finish the wizard and you will see the result:

5. Create Poll in the Backend

To create a poll in the backend, follow the steps below:

Create or open a layout of the page which will contain a poll.
Add a placeholder to the layout.

Set the ‘key’ parameter to the appropriate placeholder key.
Assign the layout to a template or an Item.
Add the ‘Voting’ control as a rendering.

Set the value of the placeholder’s ‘key’ parameter according to the ‘placeholder’ field of the rendering.
Set the VotingPath, VotingName and ArchivePath parameters.

Publish and view the results in your browser.

6. Module Structure

Poll Module Items are structured in three levels.

On the top, there is a poll folder based on the Poll Folder Template. The Editor application of this Template allows creating new polls and setting the poll of the day and connection string.

On the next level, there are poll Items based on the Poll Template. The Editor application shows the voting statistics for this Template. The Data section has a mandatory field title. The value of this field is displayed on the poll pages instead of the Item name.

On the third level, there are Items which represent poll’s options based on the Poll Option Template. These Items show one of the variants of a poll. Title is a mandatory field of the data section; it is used by client controls.

Add the Voting rendering to your custom layout.

Poll rendering parameters:

Main parameters:

VotingPath – a path to the poll folder. For example: ‘/sitecore/content/Polls’
VotingName – The poll name. For example, ‘Do you like apples?’
ArchivePath – path to the Archive page. For example, ‘/sitecore/content/Home/Archive’

Other parameters:

CanViewResults – a boolean parameter; if the value is ‘false’, the button ‘Show results’ is not visible.
ShowResults – a boolean parameter; if the value is ‘true’, a user cannot vote and the results are shown at once.
FilterByUser – a boolean parameter; if the value is ‘true’, every single user cannot vote more than once.
FilterByIP – a boolean parameter; if the value is ‘true’, every single user cannot vote more than once.

Presentation parameters:

MainClass – CSS class of the main <div> tag.
TitleClass – CSS class of the title.
FooterClass – CSS class of the footer.
PollTableClass – CSS class of the table with voting options.
PollOptionClass – CSS class of the row with voting option.
PollOptionResultClass - CSS class of the row with voting option (in the results window).
PollOptionResultTitleClass - CSS class of the row with voting option title (the results window).
SendButtonClass – CSS class of the ‘Send button’.
ViewResultsButtonClass – Css class of the ‘Result button’.
ArchiveButtonClass - Css class of the ‘To archive’ button’.
SendButtonTitle – Title of the ‘Send’ button.
ViewResultsButtonTitle – Title of the ‘Result’ button.
ArchiveButtonTitle – Title of the ‘To archive’ button.

To view the archive, use the ‘VotingArchive’ rendering. Add this rendering to a layout or add a placeholder and link it to the rendering. This rendering is a mandatory parameter:

PathToResultPage – path to the page which shows the results of the selected voting. For example: ‘/sitecore/content/Home/Results’.

Other rendering parameters:

MainClass - CSS class of the main <div> tag.
PollRowClass – CSS class of the row with the poll title.
PollRowTextClass – CSS class of the text of poll.
PollTitleClass – CSS class of the title of the archive.
ArchiveTitle – title of the archive.

The Results page must have a Voting rendering with the ‘ShowResults’ parameter set to ‘true’. The ‘ArchiveVoting’ rendering delivers ‘VotingName’ and ‘VotingPath’ by a query string. In results page, query string should be parsed in order to pass ‘Voting’ control parameters.

Your code may look like this:

private void Page_Load(object sender, System.EventArgs e)

{

...

Poll.VotingName = Request["VotingName"];

Poll.VotingPath = Request["VotingPath"];

Poll.ShowResults = true;

...

}

Use ‘PollPortlet’ to display polls in the ‘Sitecore today’ window. ‘PollPortlet’ acquires settings from the global poll setting Item.